This Introduction to Apama is for new Apama users. It provides a high-level overview of Apama, describes the Apama architecture, discusses Apama concepts and introduces Apama Plugin for Eclipse, which is the main development tool for Apama.
In addition to reading this Introduction to Apama, it is recommended that you do the following to become familiar with Apama. Work through the Apama tutorials in Apama Plugin for Eclipse. From the Help menu, choose Welcome to display the Welcome page, and then click Tutorials under the Apama heading. This displays links to interactive tutorials that provide step-by-step instructions for writing simple Apama applications that you can then run and monitor.
What is Apama?
Apama is an event processing platform. It monitors rapidly moving event streams, detects and analyzes important events and patterns of events, and immediately acts on events of interest according to your specifications.
Event-based applications differ from traditional applications in that rather than continuously executing a sequence of instructions, they listen for and respond to relevant events. Events describe changes to particular real-world or computer-based objects, for example, a new temperature reading from a factory sensor.
Events are collections of attribute-value pairs that describe a change in an object. For example, the figure below shows events from a sensor. Each sensor reading has a number of attributes, such as temperature and pressure.
The attributes, or fields, of an individual event class may be of a variety of types, including numerical and textual data. Events with multiple fields can be viewed as multidimensional types, in that a search to find an event of interest might involve searching across several of the event fields.
Rather than executing a sequence of activities at some defined point, an event-based system waits and responds appropriately to an asynchronous signal as soon as it happens. In this way, the response is as immediate (or real-time) as possible.
The main Apama features include:
Graphical development tools accessible to business users.
EPL, which is a concise, richly-featured event processing language.
The connectivity plug-in API, which allows in-correlator integration with external data sources of varying formats.
Sophisticated analytics with native support for temporal arguments.
Sub-second response to detected events and patterns of interest.
Highly scalable, patented, event-driven architecture, supporting tens of thousands of concurrent scenarios.
Flexible event replay for testing new event scenarios and analyzing existing ones.
Tools for managing and monitoring your application.
About Apama license files
License files
A license file is required for the full functionality of Apama. Refer to the licensing terms specified in your software contract for any additional legal restrictions that may be imposed on your use of Apama. You can provide the Apama license file in the following ways:
Copy the license file to the Apama work directory (APAMA_WORK/license).
Specify the path to the license file by setting the licenseFile element in the YAML configuration file for the correlator. See YAML configuration file for the correlator.
Specify the path to the license file using the -l or --license command-line option when starting the correlator executable. See Starting the correlator.
It is possible to run Apama without a license file or with an expired license file. Apama behavior with regard to the Apama license file is as follows:
A correlator started with a license file does not shut down immediately when its license expires. It continues operation for seven days beyond expiration. After that, the correlator shuts down. The correlator logs periodic warning messages until it reaches the end of the seven days or until you replace the expired license.
Removing the license file from a running correlator does not cause it to shut down immediately. It continues operation for seven days after the license file is removed. After that, the correlator shuts down. The correlator logs periodic warning messages until it reaches the end of the seven days or until you restore the license.
You can start a correlator with an expired license if it is less than seven days beyond expiration.
If you want to continue with reduced capabilities after the correlator has shut down after seven days, you have to remove the license and then restart the correlator.
If you obtain a license file after you have been running Apama, copy it to the license directory in your APAMA_WORK directory, for example: C:\Users\Public\Apama\ApamaWork_*n.n*\license\ApamaServerLicense.xml (where n.n stands for the current version number).
If the correlator’s license has expired, you have to obtain a new license file and copy it into the same location before the end of the above mentioned grace period. The correlator checks for an updated license file every five minutes, so the new license file is automatically picked up. The correlator does not need to be restarted in this case.
If you name the license file “ApamaServerLicense.xml” and put it in the license directory in APAMA_WORK, then the correlator will automatically pick up the license file. Otherwise, you must specify the path to the license file on the command line.
Note:
When you are using Apama in Cumulocity, that is, the Streaming Analytics application, a valid license is automatically provisioned. See the Cumulocity documentation at https://cumulocity.com/docs/streaming-analytics/overview-analytics/ for more information on the Streaming Analytics application.
Running Apama without a license file
Apama can be run without a license file in which case it runs with reduced capabilities and can be used for simple or exploratory use cases. Refer to License terms and technical restrictions for the current license terms and restrictions.
The following restrictions apply when starting the correlator without a license file:
The correlator does not start more than 4 threads for EPL processing. The number of threads being used is logged. Up to 20 contexts may be created and all are runnable, but the correlator does not use more than 4 threads to execute EPL, limiting the correlator’s performance.
Reliable messaging with connectivity plug-ins is not permitted.
Correlator-integrated messaging for JMS is limited to BEST_EFFORT only messaging (unreliable). It refuses to connect using reliable modes (EXACTLY_ONCE, AT_LEAST_ONCE or APP_CONTROLLED).
The correlator logs that it is running without a license file.
The following restrictions are enforced while the correlator is running and a license file cannot be found:
The correlator is limited to 1024MB of resident memory. If 1024MB of memory is exceeded, the correlator is stopped and an error is logged indicating that the correlator is running without a license file. There is a warning if the resident memory exceeds 90% of the 1024MB limit - though if the correlator’s memory increases very quickly, the limit may be hit before the 90% warning is logged.
Note that this limit also includes Java memory usage. It is recommended that you size your Java virtual machine to not consume too much memory. If you are using Java features, you may need to use -J-Xmx256M to limit the memory usage of your Java virtual machine to 256MB (or some suitable size less than 1024MB). Note that the memory usage may increase if a burst of events is received.
The correlator does not allow more than 20 contexts to be created. The spawn statement throws an exception if it would create a new context and 20 contexts are already created. In addition, a startup error occurs when recovering a persistent database with more than 20 contexts. Both the exception and the startup error indicate that the correlator is running without a license file.
The correlator does not allow more than 5 persistent EPL monitors (this does not include monitor instances of persistent monitors). An error is logged if there are more than 5 persistent monitors.
The correlator does not allow the injection of user-generated correlator deployment packages (CDPs). If a user-generated CDP is injected, the correlator rejects the injection and an error is logged indicating that the correlator is running without a license file.
The correlator does not allow more than 5 Apama query definitions to run and no more than 5 query instances per definition. When more than 5 query definitions are injected into the correlator, ERROR log messages are written.
Info
Apama queries are deprecated and will be removed in a future release.
The Apama query runtime drops events if there are already 50 different partition values for a query. When more than 50 partition values are sent in, ERROR log messages are written.
If reliable JMS connections are requested dynamically, an exception is thrown which should be caught in EPL, and an error message is logged indicating that this configuration is not supported as the correlator is running without a license file.
The correlator info web page (http://localhost:15903/info) always shows you whether the correlator is currently running with or without a license file.
To find out if the above-mentioned limits have been exceeded, you can check the following:
The -a (--getall) or -Pm (--getpmemory) option of the engine_management tool to get the physical memory usage. See Shutting down and managing components.
